What is API-first?

Why does it matter?

An API-first strategy can seriously supercharge a company’s digital transformation.

Consider the famous story of Amazon’s API-first mandate. In 2002, Jeff Bezos sent out a memo explaining that every team at the company must “expose their data and functionality through service interfaces,” and that they use “no other form of inter-process communication.” The teams also had to design these service interfaces “from the ground up to be externalizable [...] to developers in the outside world. No exceptions.”

In the aftermath of this mandate, every team at Amazon considered what resources and data they had, then made them available to other teams and external developers through an API.

This shift to API-first jump-started the company. Over a handful of years, Amazon transformed from a bookseller to a dominant, multi-billion-dollar, cloud-computing powerhouse.

Why is API-first popular today?

Two words: microservices architecture.

Many innovative businesses are ditching monolithic applications, which bundle a series of business functions and client applications into a one-size-fits-all package. Instead, they are adopting a custom approach. They mix and match software components — e.g., microservices — to build a modular tech stack that offers the functionality they need to face their unique business challenges.

APIs are essential to this kind of microservices architecture. They act as an interface layer that enables the various components in the microservices ecosystem to communicate with each other and share functionality.

You may already see why the API-first approach is so important. Because this strategy focuses on the API-first approach, it produces the most flexible and easy-to-use APIs. And this makes it easier to build out a robust microservices architecture.

API-first vs. code-first

To dig deeper into that last point, let’s compare API-first strategies against a more traditional API design process, code-first development.

A development team building a new product with this API strategy develops the app first. After that, they identified the most common use cases. Then, they build a new API that artificially exposes the necessary data and functionality for those use cases — and those use cases only.

It’s obvious here that the API design is an afterthought. That’s why code-first development often results in a less-than-optimal API, poor developer experience, and frustrating limitations. We’ll demonstrate the reasons for that in the next section.

Why pick API-first apps or platforms?

1. Full access

Remember how an API-first strategy involves building the API and then adding a user interface?

One big benefit of this strategy is that the user interface will offer access to the same data and functionality as the backend. You’ll be able to perform the same tasks, whether you opt to do them manually through the user interface or programmatically through the API.

Contrast that with a code-first API strategy. This exposes only a small subset of the app or platform’s data and functionality through the API. That limits the tasks you can complete programmatically. You’ll be able to access only the data and functionality that the developer thinks you should access — for every other task, you’ll need to work manually in the app.

2. Interoperability for easy workflows

So, we see how an API-first strategy produces an app that exposes all data and functionality to devs. This brings another huge benefit: It’s straightforward to build a tech stack where separate components — like the headless CMS, the DAM, and so on — can effectively communicate with one another.

For example, imagine you were building out a workflow for translating content in Contentful. Since Contentful is an API-first platform, you’ll have access to all the data and functionality necessary to build a connector to your translation microservice. Just use Contentful’s Read API to fetch the content, translate it, and then use the Content Management fields API to insert it back. Done.

This is powerful. You are essentially creating a composable application without writing a single line of glue code just by interacting with the API in a generic defined fashion, and using no special tools. This greatly reduces the amount of development needed to accomplish your unique goals.

3. A single source of truth

As we discussed, an API-first development process builds the backend first, then a light user interface to go on top of it. That means the UI runs on the same API as you do when it accesses and manipulates data. Whether you work with the frontend or the backend, you’re working with a single source of truth.

Compare that to a code-first strategy. Building the API to expose data and functionality at the end of the software development process requires building a second toolset for accessing and manipulating data. When you manipulate data in two different ways, that often results in two sources of truth. A recipe for disaster.

4. Automation

When an app or platform uses an API-first strategy, any task you perform through the user interface can also be performed in the backend using scripts. That means no more repetitive manual work. It also means you can build advanced workflows for tasks like syndication, migration, and even complex, large-scale data manipulation.

Here’s an example of a simple workflow built with API-first tools: Maybe you have created a space in Contentful and mistakenly chose German as the primary locale rather than English. Since Contentful uses an API-first strategy, you could write a script to handle it. Type out five or six lines of code, run it, and you’ll have a whole new space configured exactly how you want without ever needing to open the UI.

It’s also easy to build workflows for much more complex tasks. Let’s look at a real-life workflow to illustrate: One of Contentful’s customers found themselves generating a new space manually every time an internal team needed to create a microsite. (And this was happening a lot.) So, they used functionality and data exposed through the Contentful API to automate the process. 

Now, they can provision a space from a template, build it, put it up on their hosting platform, and invite users — all automatically. Internal teams can start prototyping and customizing as needed without wasting developers’ time on repetitive manual tasks.

5. Better documentation, better developer experience

When the dev team for a new product has taken an API-first strategy, they have already considered all possible uses and endpoints. So, it’s a short step to add clear, comprehensive technical documentation for the API.

These resources will clearly list the information any developer needs when implementing new workflows with the API, such as:

• All available API endpoints

• How those endpoints work

• How to deal with common errors

• Whether to work with an API specification

• What that API specification is

• Examples showing how to use the API in different languages like JavaScript, C#, or PHP

The most thoroughly considered API-first apps will even offer supportive tooling like software development kits (SDKs). Tools like these make your life easier as you work with the API in different contexts, such as mobile apps.

At this point, you might think that API technical documentation and supportive tooling are a nice bonus. But they’re actually a very big selling point for API-first platforms and apps. 

Compare this against legacy products. If you use one of these tools, you’ll quickly learn how much effort it takes to gain access to technical documentation. To add to the insult, the documentation you receive is often incomplete, outdated, or just not very useful. And that makes it difficult for your developers to accomplish their goals and help fuel your business’ digital transformation.

Now that AI is growing in popularity, documentation will be even more important than before. You can feed the documentation to AI tools, giving them the context necessary to work with specific services. That will make you even more efficient in building new tools on top of the platform.

6. Permissionless innovation

For all the reasons we listed above, an API-first app or platform supports your developers as they innovate.

Many of Contentful’s customers, for example, will look at the comprehensive API documentation that we generated with our API-first development process and say, “I see that I can get this information out of the system. And I see that I can put this information in. And this is how I can automate the process and filter the data. I can actually develop a pretty smart workflow that saves me a lot of time every week.”

Contenful’s API-first strategy gives every developer the tools they need to build their own innovative solutions. Compare that against apps and platforms that offer limited access through their API and poor documentation. They may require weeks of waiting to get the access and documentation your developers need.

Wrapping Up

API-first means the API is the primary and most important focus during the development process for a new product. 

As the end-user, it means you’ll have the best possible user experience with that API. You’ll get every tool you need to build a robust custom tech stack that solves your business problems. And you’ll be free to create innovative workflows that improve your life and save you tons of time.

In short? When you choose to work with API-first apps, your creativity is the only limitation.